ConvImgs
========

Software for RISC OS by Chris Johnson

+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  
Introduction
------------
ConvImgs is an application that allows the batch interconversion of
various image filetypes, e.g. sprite, PNG, JPEG, with the bonus that a
number of simple transformations can be carried out at the same time.

Installation
------------

For a new installation, simply drag and drop the ConvImgs application
into the directory of your choice.

If you have a previous copy of ConvImgs you should move the old
version of ConvImgs somewhere safe and replace it with the new
version.

Usage
-----
ConvImgs is run in the usual way by double clicking on its icon. It
will install on the icon bar.

The file, or selection of files, to be converted should be dragged to
ConvImgs, either to the iconbar icon, when the control window will
open, or if the control window is already open, files may be dragged
to it.

The selection of files can be added to by dragging further selections.
In addition, if one or more folders are dragged, then ConvImgs will
add any suitable image files in the folder to the list.

ConvImgs will NOT recurse down the directory structure, only suitable
image files in the top level will be added to the queue for
processing. This is a deliberate decision - the worst case scenario
with full recursion is that every image file on your 200GB drive is
converted to eg. PNG format!

For any particular batch process, the types of the files to be
converted need not be all the same - ConvImgs will queue for
processing any image type it is able to load. It is currently able to
load the following filetypes.

  Sprite
  JPEG
  PNG
  TIFF
  BMP
  GIF
  Sprite in a draw file (the first one found)

Notes on memory usage
---------------------

When ConvImgs loads an image, it first converts it to an internal
format RGB raster. If the original image is a full colour (16 million
colour) image then it will be stored in 32 bpp (bits per pixel) mode.
An image of dimension 4000  3000 i.e. 12 Mpx, (not particularly
large by modern digital camera standards), would occupy 48 MB of RAM.
If image transformations are being applied, then some of these require
memory to be allocated to store the 'new' image as the transformation
is applied. This may double the storage memory requirement during the
transformation. Thus the size of image that can be converted will be
limited by the amount of RAM available. Recent native hardware, such
as PandaBoard, Raspberry Pi, iMX6, Titanium, which have at least 512
MB, perhaps 2 GB, of RAM would have no problem with very large images,
whereas older hardware might run out of memory.

+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  
The iconbar icon
----------------
If a selection of suitable image files is dragged to the iconbar icon,
these files will be added to the list of files to be processed. The
control window will open automatically if not already open.

Clicking with SELECT on the iconbar icon will open the control window.

The icon bar menu
-----------------
Info
~~~~
Shows application information, including the version number, and also
contains a Web button to check the download site for new versions.

Help...
~~~~~~~
Opens the html help file (this one).

Control...
~~~~~~~~~~
Open the ConvImgs control window (see here). The control window can
more easily be opened by clicking on the icon bar icon with Select.

Choices...
~~~~~~~~~~
Open the ConvImgs choices window (see here). This allows you to change
certain general settings, and also determine the settings in force
when ConvImgs first starts up.

Quit
~~~~
Remove the application from the iconbar.


+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

Choices...
----------
The Choices... window, is accessed from the iconbar icon menu.

Limit multitasking during processing
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
When the conversion is started, ConvImgs will always poll the wimp in
between each individual operation of the conversion (eg between the
file load and the file save). If this option is unticked, then
ConvImgs will also poll the wimp during each operation. In most cases
this means after each row of pixels of the image is processed. This
will be slower, but the machine will remain fully responsive as the
conversions are carried out. If it is ticked, then an hourglass will
be shown during each phase of the conversion while there is no
multitasking.

Add file extension
~~~~~~~~~~~~~~~~~~
If this is ticked then ConvImgs will add the appropriate file
extension (eg /jpg or /png) to the filename of each file as it is
saved. If not ticked then the original filename, stripped of any
extension it had, will be used for the saved file.

The additional option Long extension will use eg jpeg instead of jpg,
where such alternative extensions exist.

Retain original date/time stamp
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If this is ticked then the converted files will have their date/time
stamp set to that of the original file. When unticked, the converted
file will have a date/time stamp corresponding to when the processed
file was saved.

Auto select process option when changed
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This is for those of us who set up e.g. resize options, but then
forget to select the option button to make the setting be used in the
conversion. If this is ticked, then the appropriate option button will
be automatically selected when a processing option is changed.

At the bottom of the window are three action buttons.

Set
~~~
When this button is clicked, ConvImgs will use the new settings for
subsequent conversions.

Save
~~~~
When this button is clicked, ConvImgs will use the new settings for
subsequent conversions, and will save the settings so they are
restored when ConvImgs is run on a subsequent occasion.

Cancel
~~~~~~
When this button is clicked, the window will be closed and any changes
made will be ignored.


+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

The control window
------------------

In the top section is shown information about the selection of files
waiting to be converted.

Files to convert
~~~~~~~~~~~~~~~~
This shows the total number of files waiting in the queue to be
processed.

Clear file list
~~~~~~~~~~~~~~~
Clicking this button allows the file list to be cleared if you change
your mind about files in the list. It will clear the whole list.

File types
~~~~~~~~~~
This shows a breakdown of the different filetypes in the queued
selection.


The middle section of the window allows a number of standard
transformations to be applied. In this version the following
transformations are available.

  Rotate/flip
  Resize
  Histogram
  Filter
  Colour
  Convert to greyscale
  Invert image colours

These are all described in detail in the next section.

At the bottom of the window are the settings for the saving of the
converted files.

Save to
~~~~~~~
This shows the path in which the converted files will be saved. This
directory can be set in three ways.

1. Click on the menu button to the right of the path field and drag
the directory icon in to the destination directory

2. Drag the destination directory from a filer display in to the path
field. It must be in to the field, anywhere else in the window will
result in ConvImgs searching the directory for suitable image files to
be processed.

3. For the masochists, the path may simply be entered from the
keyboard.

Save as
~~~~~~~
This shows the format to which the files will be converted. The format
can be changed by clicking on the popup menu button to the right of
this field. This will open a small dialogue box, shown below.

This allows the output filetype to be set. The JPEG quality may be
set, for when saving as JPEG files. The SET button should be clicked
to apply the new settings.

At the bottom left of the control window is the Save settings button.
Clicking this button will save all the current settings so that they
will be remembered over a restart. This excludes the file list and the
save path.

At the bottom right of the control window is the Convert button.
Clicking this button will start the conversion process, assuming there
are files waiting in the queue. The control window will close, and the
status window will open.

+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

Process options
---------------
If you are a user of DPScan (by David Pilling) the process options
available here will be familiar to you - the options use the same code
library. If you are not sure how or when some of these options would
be useful, and you have DPScan, then use it with some test images to
see the possibilities.

Rotate/flip
~~~~~~~~~~~
If this option is ticked, each image will be transformed by rotation
or flipping before type conversion and saving. The current setting for
transform type is shown to the right, and may be changed by clicking
on the popup menu button and selecting a new setting from the menu
that appears.

The options available are:
  rotate left 90
  rotate 180
  rotate right 90
  flip horizontal
  flip vertical

Note that there is no 'Auto-rotate' option - only some types of file
can store orientation information, and even with those files, it is
optional. If you wish to 'auto-rotate' jpeg images from e.g. a digital
camera, then use my other application !TransJPEG (available from my
web site) to do this.

Resize
~~~~~~
If this option is ticked, each image will be transformed by resizing
before type conversion and saving. The current setting for resizing
method is shown to the right, and may be changed by clicking on the
popup menu button. A dialogue box will be opened.

There are currently four options for resizing.

Resize by
  This will rescale the image by the percentage shown in the field to
  the right.

Resize X to
  This will scale the images to the width (in pixels) entered in the
  field to the right. The aspect ratio of the image will be preserved.

Resize Y to
  This will scale the images to the height (in pixels) entered in the
  field to the right. The aspect ratio of the image will be preserved.

Fit within
  This will resize the images such that they fit within the height and
  width values specified. If the button Ignore aspect is not ticked then
  the aspect ratio will be preserved. If it is ticked then the image
  will be stretched in one of the directions to completely fill the
  specified size.

If the option 'Allow scale up' is ticked, then the images will be
scaled up if necessary to fit the size, otherwise images smaller than
the set dimensions will be left as is. This setting applies only to
the last three options. If the 'Resize by' value is greater than 100%,
then this will always be honoured.

The SET button should be clicked to apply the new settings.

Histogram
~~~~~~~~~
If this option is ticked, the range of pixel intensities in the image
will be expanded to cover the full range from black to white.

The current setting for histogram expanding is shown to the right, and
may be changed by clicking on the popup menu button. A dialogue box
will be opened.

This allows the setting of

  the number of intensity levels used in the calculation, currently 32
  to 256, the maximum
  
  the intensity threshold (as a percentage of the maximum intensity in
  the image) used when searching the histogram for levels to discard at
  each end

The SET button should be clicked to apply the new settings.

A fuller description of this option may be found here.

Filter
~~~~~~
If this option is ticked, each image will have a filter applied before
type conversion and saving. The filter that will be applied is shown
to the right, and may be changed by clicking on the popup menu button.
The current options are:

Various levels of sharpening or blurring are available. The option
'Slight sharpen' is probably the one to use to reduce the softness of
digital camera images.

Colour
~~~~~~
If this option is ticked, each image will have colour processing
applied. The type of processing to be applied is set by clicking on
the menu button to the right of this field, and follows closely the
operation of similar features in DPScan.

You can select the type of colour processing by selecting one of the
radio icons non-linear or balance.

Non-linear allows the gamma to be changed. Values of gamma less than
unity will brighten the mid-tones of the image, while values greater
than unity will darken the mid-tones of the image. It is possible to
operate on all three colour channels at the same time (the default) or
on one or two colour channels, using Select and/or Adjust accordingly.
Levels changes the number of straight line segments used to
approximate a gamma curve.

Balance allows the brightness and contrast of the image to be
modified. It operates in the same way as DPScan - values greater than
0 will increase brightness or contrast, values less than zero will
decrease them.

The SET button should be clicked to apply the new settings.

Convert to greyscale
~~~~~~~~~~~~~~~~~~~~
This will convert the image to a greyscale image. There are no
additional settings for this option.

Invert image colours
~~~~~~~~~~~~~~~~~~~~
This option will invert all the colours in the image, and is probably
of most use for black and white line art images. Some users have found
it useful when scanning diagrams as TIFF files, which then come out as
'negative' in some software.

There are no additional settings for this option.

+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

The status window
-----------------
When the Convert button is clicked, assuming there are some files in
the queue, the control window will close, and the status window will
open.

There are four display fields which show the progress of the
processing. The total number of files to process, and the position in
the queue of the current file are shown. The filename of the current
file is also shown. There is also a field that shows the current
operation being carried out.

If this window is expanded to full size, you will find two buttons at
the bottom to allow some control over the processing.

Pause
~~~~~
This will allow the conversion process to be paused. The button text
will change to Resume, and clicking on it again will result in the
conversion being continued.

Stop
~~~~
ConvImgs will first ask whether you really want to stop the
conversion. If you do, then the conversion will be stopped as soon as
possible. The current action (eg load) will be completed and then the
conversion will be stopped.

+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

Screenshots
-----------
All the screen shots in these pages were obtained using Snapper, a
versatile screen capture application.

Snapper is available from
http://www.chris-johnson.org.uk/software/snap.html

Acknowledgement
---------------
Thanks must go to David Pilling, who not only is always very helpful
and supportive, but has also made available source code used in some
of his own applications (e.g. SyncDiscs, Snapper, and DPScan).

Contact
-------
All communication about ConvImgs should be directed to Chris Johnson
(Email:chris@chris-johnson.org.uk). Suggestions for new features are
always welcome.

Web sites
---------
Chris Johnson's web site is at
http://www.chris-johnson.org.uk/index.html, with his RISC OS software
at http://www.chris-johnson.org.uk/software/index.html.

This document last modified on 26th May 2016

+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

Licence
-------

ConvImgs

Copyright (c) 2013, Chris Johnson
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:

* Redistributions of source code must retain the above copyright
  notice, this list of conditions and the following disclaimer.

* Redistributions in binary form must reproduce the above copyright
  notice, this list of conditions and the following disclaimer in the
  documentation and/or other materials provided with the distribution.


THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
